package com.mercycrazy.recruit.service;

import com.mercycrazy.recruit.user.*;

/**
 * 用户鉴权相关服务接口定义
 *
 * @author <a href="mailto:1443424326@qq.com">mercycrazy</a>
 * @since 2023-01-14
 */
public interface IUserAuthService {

    /**
     * <h2>发送短信验证码</h2>
     * 限制相同 IP 60s 内只能发送一次, 短信验证码 30 分钟内有效
     *
     * @param mobile 手机号
     * @param validTime 短信内容: 有效时间(单位: 分钟)
     */
    void sendSMSCode(String mobile, long validTime);

    /**
     * <h2>根据手机号注册用户</h2>
     */
    UserInfo registerUserByMobile(String mobile);

    /**
     * <h2>用户登录并返回 Token</h2>
     * 如果手机号不存在, 走先注册后登录逻辑, 一键注册登录
     *
     * @param mobileAndCode 手机号和验证码
     */
    UserLoginInfo loginAndGenerateToken(MobileAndCode mobileAndCode);

    /**
     * 生成二维码令牌
     */
    String generateQrToken();

    /**
     * <h2>手机端使用 HR 角色进行扫码操作</h2>
     *  1. 需要用户在手机端登录才能操作
     *  2. 从 token 中解析出的用户信息判断该用户是否具有 HR 身份
     *  3. 生成 preToken 并返回, 5 分钟有效
     */
    String scanCode(String qrToken);

    /**
     * <h2>二维码是否已经被扫码</h2>
     *  1. 前端每隔 3s 定时查询该接口, 用于页面的展示标记判断
     *  2. 前端判断二维码已经被扫码后应该立即清除判断二维码是否被扫描的定时器
     *  3. 为了限制用户在页面不操作而频繁发起调用, 30 次查询后还未被扫描: 【页面失效, 请刷新后再执行扫码登录!】
     *  4. 基于以上情况, 二维码扫描后重置超时时间 5min, 而前端 90s 内直接失效, 所以按道理后端不可能出现二维码扫描后 redis key 失效,
     *     这种情况一定是发生了异常, 应该和传入错误的 qrToken 同样处理
     */
    Boolean qrTokenHasBeenScan(String qrToken);

    /**
     * APP 确认登录到 SAAS 端(扫码登录方式)
     */
    void confirmSaasLogin(String qrToken, String preToken);

    /**
     * 网页端定时尝试登录
     *  1. APP 端确认登录后会往 redis 中存入用户信息
     *  2. 网页端查询到 redis 中存在用户信息则表示已经登录, 生成 token 返回, 跳转页面
     */
    UserLoginInfo checkLogin(String qrToken);

    /**
     * Admin 运营端登录
     *  1. 密码要进行加盐处理
     *  2. 盐保存在 DB, 每个人的盐都不相同
     */
    AdminLoginInfo adminLogin(UsernameAndPassword usernameAndPassword);
}
